MAXScripting FumeFX

FumeFX 6 >

MAXScripting FumeFX

MAXScript is a powerful 3ds Max language that allows users to customize their interface, automate tasks, or increase functionality. FumeFX`s open architecture facilitates the use of this tool, which means you can tailor FumeFX to meet your own needs. Refer to the 3ds Max Reference Guide for general information on how to use this tool.

Globals

Here is a list of global variables exposed to MXS.

ffxSilent - No Message box will show up (like Stop/Continue).

Adding/Removing objects

Here is a list of all functions exposed by FumeFX Geometry Source.

<integer>NumObjects()

Returns the number of objects.

<node>GetObject <integer>index

Returns object.

index - its range goes from 0 to NumObjects()-1

<boolean>AddObject <node>node

It will add an object to the list. No duplicates or unsupported objects will be added.

<boolean>RemoveObjectByNode <node>node

Removes object based on the node.

<boolean>RemoveObjectByIndex <integer>index

Removed object based on the object`s index.

Saving and Loading Presets

Here is a list of all functions exposed by FumeFX.

SavePresets <filename>presetFile

This saves all current FumeFX settings to a preset file "presetFile.fxp" in default preset folder. The output returns false on error.
If user provides a full path to the preset file (like c:\\mypresets\\explosion.fxp) then the preset file will be saved to the specified folder.

LoadPresets <filename>presetFile <rollout_names_array>rollouts

Use this to load all or some of the controls from the preset file "presetFile.fxp". The output returns false upon error.

If user provides a full path to the preset file (like c:\\mypresets\\explosion.fxp) then the preset file will be loaded from the specified folder.

The Rollouts parameter is an array with some of the following values:

all: load all rollouts

grid: load all rollouts from Grid Tab

sim: load all rollouts from Simulation Tab

render: load all rollouts from Render Tab

illum: load all rollouts from Illumination Tab

grid_dim: load Grid Tab / General Parameters Rollout

grid_play: load Grid Tab / Playback Rollout

grid_rec: load Grid Tab / Recording Parameters Rollout

sim_main: load Simulation Tab / Simulation Rollout

sim_smoke: load Simulation Tab / Smoke Rollout

sim_fuel: load Simulation Tab / Fuel Rollout

sim_temp: load Simulation Tab / Temperature Rollout

sim_fm: load Simulation Tab / Fluid Mapping Rollout

render_main: load Rendering Tab / Rendering Parameters

shader: load Rendering Tab / Shader Rollout

Examples:

-- have FumeFX01 save its settings to file mypreset.fxp in default presets folder

$FumeFX01.SavePresets "mypreset1"

-- have selected FumeFX object load Render Tab > Render parameters rollup and Simulation Tab > Fuel rollup from file mypreset1.fxd.

$.LoadPresets "mypreset1" #("render_main", "sim_fuel")

-- have FumeFX01 load all rollouts in Grid Tab from file mypreset.fxd.

$FumeFX01.LoadPresets "mypreset" "grid"

Adding/Removing objects, lights, sources

<integer>NumSources()

Returns number of sources.

<node>GetSource <integer>index

Returns source.

index - its range goes from 0 to NumSources()-1

<boolean> AddSource <node>source

Use this to attach FumeFX Sources to FumeFX. It is equivalent to picking a Source object in the Objects panel of the Floater Window.

<boolean> RemoveSource <node>source

Use this to remove Force FumeFX Sources from FumeFX. It is equivalent to removing a Source object in the Objects panel of the Floater Window.

<boolean> AddForce <node>force

Use this to attach Force objects like Wind to FumeFX. It is equivalent to picking a Force object in Objects panel of the Floater Window.

<boolean> RemoveForce <node> force

Use this to remove Force objects like Wind from FumeFX. It is equivalent to removing a Force object in Objects panel of the Floater Window.

<integer> NumObjects()

Returns a number of objects that are currently picked.

<maxObject>GetObject <integer>index

Returns object based on index (zero based index).

<boolean>AddLight <node>node
Adds a light

<boolean>RemoveLight <node>node

Removes light

<integer> NumEffectors()

Returns a number of Effectors that are currently picked.

<maxObject>GetEffector <integer>index

Returns Effector based on index (zero based index).

<integer> NumSpaceWarps()

Returns a number of objects that are currently picked.

<maxObject>GetSpaceWarp <integer>index

Returns SpaceWarp based on index (zero based index).

Shader Access

<maxObject>GetShader()

Returns current shader.

<boolean>SetShaderByName <string>name

Sets current shader based on name.

<boolean>SetShaderByIndex <integer>index

Sets current shader based on index (zero based).

Simulation Control

<void>CancelSimulation()

This command will cancel the simulation

<void>StopSimulation()

This command will stop the simulation. This means it will finish the current frame and save stop/continue data according to the preferences settings.

<void>RunSimulation <integer>simMode

This does exactly the same as hitting the start button on the FumeFX Floater. Simulation will run from StartFrame to EndFrame.

simMode - 0 - Default Simulation

1 - Simulation from Initial State

2 - Wavelet Simulation

3 - Retimer

<void>ContinueSimulation <integer>simMode

This does exactly the same as hitting the continue button on the FumeFX Floater

simMode - 0 - Default Simulation

1 - Default Simulation

2 - Wavelet Simulation

<boolean>SetInitialStateFile <filename>filename

Use this command to set Initial State file to be used with Initial State Simulation Mode.

<filename>GetInitialStateFile()

Returns Initial State file name.

SaveOutput <filename>outputFile

This saves a .fxd type output file; note, you must enter the full file name. Output returns false on error.

SaveSim <filename>presetFile

This saves a .fdc type simulation file; note, you must enter full file name. Output returns false on error.

<boolean>LoadSim <filename>filename

This will load a .fdc file into the FumeFX.

<filename>GetPath <string>type

This returns the current base output file name without the frame number suffix.

cacheType -default - path for Deault Sim. caches

wavelet- path for Wavelet Sim. caches

retimer - path for Retimer caches

illummap - path for Illumination Map

preview - path for preview animation clip

presets - path for presets

defaultpreset - path for the default preset file (Preferences)

scrsim - FumeFX MXS file

<boolean>SetPath <filename>path <name array>params

params -match- if grid is of different proportions, FumeFX will be matched to it.

default - path for Deault Sim. caches

wavelet- path for Wavelet Sim. caches

retimer - path for Retimer caches

illummap - path for Illumination Map

preview- path for preview animation clip

defaultpreset - path for the default preset file (Preferences)

nocheck - path validity won`t be checked.

scrsim - FumeFX MXS file

This sets output file name. You must enter the path and base file name; the extension is not necessary.

Examples:

$FumeFX01.SetPath "F:\\temp\\FumeFX\\aa"

$FumeFX01.SetPath "F:\\temp\\FumeFX\\aa.fxd"
$FumeFX01.SetPath "F:\\temp\\FumeFX\\aa.fxd" #("default", "nocheck")

$FumeFX01.SetPath "F:\\temp\\FumeFX\\aa_0000.fxd" #("default","match")
For #match, if you omit _0000 (or any existing frame number), FumeFX and cache won`t be checked for grid dimensions and won`t be matched if grid and cache have different sizes.

<void>DeleteCaches <string>name

This command will delete all the cache files

Name -default- path for Default Sim. caches

wavelet- path for Wavelet Sim. caches

retimer- path for Retimer Sim. caches

illummap - path for Illumination Map. caches

<boolean>ExportRenderingParams <string>name

This will save current frame rendering params to the file.

Misc. Functions

<int>GetBBox <point3>&dim0 <point3>&dim1

This command will return the cache number that is currently loaded and FumeFX bounding box in local coordinates. The return number of -99999 could indicate that there was no cache loaded in memory at the time this function was called.
Returned values in dim0 and dim1 are corners of the bounding box.

Example:
min=[0,0,0]

max=[0,0,0]

$.GetBBox &min &max

<int>GetFireInfo<float>&min <float>&max <float>&avg

<int>GetSmokeInfo<float>&min <float>&max <float>&avg
<int>GetTempInfo<float>&min <float>&max <float>&avg
<int>GetVelInfo<float>&min <float>&max <float>&avg

This command will return the cache number that is currently loaded. The return number of

-99999 could indicate that there was no cache loaded in memory at the time this function was called or that channel was not present inside the cache.

min - returns the minimum channel value inside the grid

min - returns the maximum channel value inside the grid

avg - returns the average channel value inside the grid (empty voxels are excluded).
After the simulation is finished FumeFX will load channels depending on the viewport or requirements. To force channel to be loaded you should enable its display inside the viewport.

FumeFX MAXScript Functions for Accessing the Simulation

By learning to use FumeFX functions created for MAXScript, you can do almost anything that you want with FumeFX - including things not provided for in the default user interface. It is possible for you to plug in script between all significant phases of the simulation or even disable some simulation steps altogether.

In this version of FumeFX, MAXScript cannot be called from the Listener, Macro Scripts, or in any other way except from within FumeFX while the simulation is running or the output is being loaded. Preparation of the scripts takes place in the General panel of the Floater Window. You can access this by clicking the Edit Script button in the MAXScript rollout.

If you create a script that will modify all of the voxels in a simulation (which could be tens of millions), it will execute at reasonable speeds, measured in seconds.

To get the feel of it, here is an example script:

fn PostObjects = (

for i in 0 to (nx - 1) do

for j in 0 to (ny - 1) do

for k in 0 to (nz - 1) do(

val=k/(nz as float)

SetSmoke i j k val

)

PostObjects is a "callback" function that FumeFX will call in every frame of the simulation after it has applied all sources and objects. It will go through all voxels in the adaptive grid (nx, ny and nz are global variables provided by FumeFX) and initialize the Smoke channel with a vertical gradient going from 0 to 1 over the local Z-axis. Channel is set using voxel coordinates.

MAXScript in FumeFX Simulation

How it works:

When you click Edit Script in the Simulation group, you will see a template in which to write your scripts. In it there are certain MAXScript functions that FumeFX will call during simulation. All of them are called once for each step of the simulation, unless otherwise noted.

Callback Functions

Note: Currently, the PostAdvection and PostPressure functions are for experimental use only, but are provided for those who are familiar with their use.

PreSim: Called once - at the beginning of simulation, before the first step has started, but after possible snapshot or stop/continue data has been loaded.

PostSim: Called once - after the last step of the simulation has ended and while the simulation results are still in memory.

PostObjects: Think of this as a scripted Source. It is called after the Adaptive grid has adjusted and FumeFX Sources, objects, and forces have all been applied. Here, you can additionally initialize the grid any way you like.

Vorticity: This is the only place where Vorticity can be customized. The AddVort function allows every voxel can have its own Vorticity strength. Be aware that the stability of simulation can become unreliable when using values greater than 1.

PostForces: Buoyancy, Gravity, Vorticity, Motion Drag have been applied. Here you can apply custom forces such as: radial gravity, motion drag dependent on object distance, etc???

PostAdvection: This is called after Velocities have moved through one step. If you have disabled FumeFX`s Advection phase, you could theoretically write your own version in this function.

PostDiffuse: This is called after movement of Smoke and Fuel and their diffusion and dissipation. This is the proper time to set Fuel and Temperature values to control fires.

PostStep: This is called following a whole simulation step, after the Fuel has been burned and diffusion and dissipation applied. You can set any kind of influence between channels here. If you have disabled FumeFX`s Burn phase, you could use this to burn Fuel your way.

Skipping FumeFX Simulation Phases

If you want to skip certain FumeFX simulation phases completely, uncomment in the template, or write the following statements on the global level of the script:

skipForces = true

skipAdvectFields = true

skipAdvectVels = true

skipPressure = true

skipBurn = true

This is not recommended unless you have experience.

A few examples of when you can skip certain phases are:

You can skip Pressure and Advection phase if you simulate only the effects of diffusion.

You can skip the Burn phase if you want to burn Fuel some other way.

You can skip Forces if you want to apply buoyancy, gravity or motion drag in some specific way, such as depending on position or distance from objects.

So, what can you do within these functions? Basically, you can get and set values for the main channels: Smoke, Fuel, Temperature and Velocity. You can also stop or cancel simulation and write messages to the FumeFX status window.

Simulation Control Functions

ffxPrintToStatus <string>message

This prints message to FumeFX status window during simulation.

ffxStopSimulation()

This is equivalent to pressing the Stop button in the status window.

ffxCancelSimulation()

This is equivalent to pressing the Cancel button in the status window.

ffxHoldWindowOnce()

If this function is called during simulation, then after the simulation has stopped or cancelled, the simulation window will stay open, regardless of Hold Window checkbox selection.

Get Channel Functions

Smoke is used in this example; however, all other channels are analogous. The ways to get Smoke values are:

GetSmoke <integer>i <integer>j <integer>k

In this function, i, j, and k respectively represent the X, Y, and Z-axis coordinates in an adaptive grid. Voxel coordinates can range from 0 to nx-1 for i, 0 to ny-1 for j, and 0 to nz-1 for k. So, to get the smoke value in first voxel you would write

GetSmoke 0 0 0

Or, to get it from the top center voxel you would write:

GetSmoke (nx/2) (ny/2) (nz)

GetSmokeByIndex <integer>index

This is slightly faster than the form GetSmoke i j k. It uses only one parameter, voxel index, which is computed (i*ny + j)*nz + k.

To get the average value of smoke

average = 0.0

for ind in 0 to (voxels-1) do (average += GetSmokeByIndex ind)

average /= voxels

GetSmokeLocal <point3>lpt

Here lpt is a point in a FumeFX object or local space. Unless the pivot is moved, the center of that coordinate system is the bottom center point of the FumeFX object. FumeFX dimensions are exposed through FumeFX nodes: Width, Length, and Height.

GetSmokeLocal [10.0, 10.0, $FumeFX01.Heigth/2]

GetSmokeWorld <point3>wpt <matrix3>FumeFXt

Here wpt is a position in world coordinates. You must also provide a FumeFX transformation matrix.

To get Smoke density at some object`s position

wpt = $sensor01.position

tm = $FumeFX01.transform

if ((GetSmokeWorld wpt tm) > threshold) then myfunction()

These functions will return undefined if you ask for non-existing coordinates or coordinates outside of the grid. They will also return undefined if the channel has not been allocated - for example GetFuel() if Simulate Fire has been turned off in the Simulation tab.

A complete list of Get functions:

float GetSmoke

float GetSmokeByIndex

float GetSmokeLocal

float GetSmokeWorld

float GetTemp

float GetTempByIndex

float GetTempLocal

float GetTempWorld

float GetOxy

float GetOxyByIndex

float GetOxyLocal

float GetOxyWorld

float GetFuel

float GetFuelByIndex

float GetFuelLocal

float GetFuelWorld

point3 GetVel

point3 GetVelByIndex

point3 GetVelLocal

point3 GetVelWorld

Usage of functions:

GetChannel i j k

GetChannelByIndex index

GetChannelLocal lpt

GetChannelWorld wpt TM

Index and i,j,k coordinates must be passed as integers.

Set Channel Functions

To set channel values, functions are provided that are analogous to the Get functions. They only have one additional parameter - value to set. Input ranges are not checked - so accuracy is important. The output can return true or false even if the value was, for some reason, not set.

These functions set value at one voxel only - the voxel that the point belongs to.

SetSmoke <integer>i <integer>j <integer>k <float>value

This uses adaptive grid voxel coordinates.

SetSmokeByIndex <integer>index <float>value

This uses voxel index.

SetSmokeLocal <point3>lpt <float>value

This uses FumeFX local coordinates.

SetSmokeWorld <point3>wpt <matrix3>FumeFXtm <float>value

This uses world coordinates.

A complete list of Set functions:

float SetSmoke

float SetSmokeByIndex

float SetSmokeLocal

float SetSmokeWorld

float SetTemp

float SetTempByIndex

float SetTempLocal

float SetTempWorld

float SetOxy

float SetOxyByIndex

float SetOxyLocal

float SetOxyWorld

float SetFuel

float SetFuelByIndex

float SetFuelLocal

float SetFuelWorld

point3 SetVel

point3 SetVelByIndex

point3 SetVelLocal

point3 SetVelWorld

Usage of functions:

SetChannel i j k value

SetChannelByIndex index value

SetChannelLocal lpt value

SetChannelWorld wpt TM value

Smoke, Fuel and Temperature are float channels, and Velocity is a point3 channel. Remember to set the point3 channels with the point3 values, for example:

SetVelByIndex index [x,y,z]

More Channel Functions

There are also functions for Vorticity and Turbulence. Used in simulation, they are cumulative with UI defined global Vorticity and Turbulence. If you wish to use only the scripted values, you must set Vorticity and Turbulence strength in the UI to 0.

Note: Vorticity strengths above 1 may, in rare cases, make the simulation unstable.

To add Turbulence, you can use:

AddTurb <integer>i <integer>j <integer>k <float>value

AddTurbByIndex <integer>index <float>value

AddVort functions can only be used during Vorticity callback.

AddVort <integer>i <integer>j <integer>k <float>value

AddVortByIndex <integer>index <float>value

You can fill the entire channel with a given value using the following functions:

FillSmoke <float>value

FillFuel <float>value

FillTemp <float>value

FillVel <point3>value

MAXScript after Loading Output

It is possible to post-process FumeFX output files at the time of loading. Here, for example, you can change the displayed result or the result used by the particles without affecting the simulation. Appropriate callback is called PostLoad.

Example: To set smoke to any given minimum value throughout the entire grid, achieving a fog-like effect, enter the following script.

fn PostLoad = (

sm = 1.0 -- desired minimum smoke value

for i in 0 to (voxels-1) do

(

s = GetSmokeByIndex i

if (s < sm) then ( SetSmokeByIndex i sm )

)

Switching Between Coordinates

If you want to make modifications to FumeFX voxels, you will most often run loops in voxel space or index range. However, you may need to do some calculations in local or world space for some modifications. For this and similar cases, converter functions exist between various coordinate spaces that FumeFX uses.

List of functions:

<integer> ffxVoxelPtToIndex <point3>vpt

<point3> ffxVoxelPtToLocal <point3>vpt

<point3> ffxVoxelPtToWorld <point3>vpt

<point3> ffxIndexToVoxel <integer>ind

<point3> ffxIndexToLocal <integer>ind

<point3> ffxIndexToWorld <integer>ind

<integer> ffxLocalPtToIndex <point3>lpt

<point3> ffxLocalPtToVoxel <point3>lpt

<point3> ffxLocalPtToWorld <point3>lpt

<integer> ffxWorldPtToIndex <point3>wpt

<point3> ffxWorldPtToVoxel <point3>wpt

<point3> ffxWorldPtToLocal <point3>wpt

VoxelPtTo??? functions take point3 as argument, in adaptive grid coordinates, ranging [0.,0.,0.] - [nx, ny, nz].

IndexTo??? functions take integer as argument, ranging from 0 to (voxels-1).

LocalPtTo??? functions take point3 as argument, in FumeFX local coordinates, ranging from [-Width/2, -Length/2, 0.] - [Width/2, Length/2, Height] for values inside the FumeFX grid.

WorldPtTo??? functions take point3 as argument, in world coordinates.

IndexTo??? functions must get valid index or they return undefined, other functions will convert between spaces regardless of whether the point is within FumeFX grid or not.

???ToVoxel functions return point3 ranging from 0 to [0.,0.,0.] - [nx, ny, nz].

???ToIndex functions return integer ranging from 0 to (voxels-1).

???ToLocal functions return point3 ranging from 0 to [-Width/2, -Length/2, 0.] - [Width/2, Length/2, Height] for values inside FumeFX grid.

???ToWorld functions return point3 in world space.

Various Issues

FumeFX will execute MAXScript commands in a single thread, but the usual simulation phases still execute in multiple threads. So, if you do heavy scripting you can expect some slowdowns.

If you Get and Set just a few channel values at once, you will not have to be concerned with memory issues. However, should you want to keep a copy of a whole channel in memory as a MAXScript array, you will have to enlarge MAXScript`s heap size. To do this, go to Customize -> Preferences -> MaxScript tab -> Memory group -> Initial heap allocation. To copy a float channel with 1 million voxels to MAXScript`s array you will need 28MB of MAXScript Heap memory, and for a point3 channel you will need 36MB.

If you no longer need such a big array or if you want to overwrite it, do the following:

arrayname = #() -- make it an empty array

arrayname = undefined -- or undefine it completely

gc light:true -- wipe it from memory

The statement "gc" invokes the MAXScript garbage collector. Otherwise, if the array takes most of the MAXScript heap, just writing to the same array twice may take an incredibly long time. See the "Memory Allocation and Garbage Collection" and "Manual Garbage Collection" in the MAXScript User Reference for more detail.

Notes

You have to provide valid values to FumeFX when you set them.

For Fuel, ranges are -100 to 100. Set negative values to have fuel in non-burning state, or set positive values to have already burning fuel.

If you want to use the time slider`s global variable in FumeFX scripts, add one frame to it. FumeFX sets the time slider when it has finished calculating a frame. For example, when calculation of frame 5 is in progress, the slider time global variable will still be at frame 4.